<HTML><HEAD><TITLE>viewable_expand(++ViewableName, ++DimensionNumber, +ExtraElements, ++LocName)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(viewable)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>viewable_expand(++ViewableName, ++DimensionNumber, +ExtraElements, ++LocName)</H1>
Expand a dimension of a viewable by adding new elements, specifying the name of the new location.
<DL>
<DT><EM>ViewableName</EM></DT>
<DD>A string or atom; the name of an existent viewable
</DD>
<DT><EM>DimensionNumber</EM></DT>
<DD>An integer: the number of the dimension to be enlarged.
</DD>
<DT><EM>ExtraElements</EM></DT>
<DD>A nested list or an array of the right size/dimensions, containing the new viewable elements.
</DD>
<DT><EM>LocName</EM></DT>
<DD>A string: the name of the new location.
</DD>
</DL>
<H2>Description</H2>


        <p><B>NOTE:</B>When there are no registered visualisation clients,
        this predicate succeeds with any arguments, and has no effect.</P>

        <p>This predicate behaves exactly the same as <code>viewable_expand/3</code> except that you have the added ability to name the new location of the expanded dimension. <em>LocName</em> is a string which becomes the name for the new location. </p>

        For more details on expanding viewables, see the documentation for <code>viewable_expand/3</code>. 


<H3>Fail Conditions</H3>
Fails if ViewableName is not the name of an existent viewable, or if the requested dimension of the viewable is not flexible.
<H3>Resatisfiable</H3>
no
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>ViewableName is not a string or atom
<DT><EM>(5) type error </EM>
<DD>DimensionNumber is not a ground integer
<DT><EM>(6) out of range </EM>
<DD>DimensionNumber is not positive, or exceeds the viewable's number of dimensions
<DT><EM>(1) general error </EM>
<DD>ExtraElements is not a regular nested list or array of the correct size/dimensions
<DT><EM>(5) type error </EM>
<DD>ExtraElements contains elements which do not conform to the element type of the viewable
<DT><EM>(5) type error </EM>
<DD>LocName is not a string
</DL>
<H2>Examples</H2>
<PRE>

[Assuming that at least one visualisation client is registered]

       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
       	               array([flexible, fixed], any)), 
       viewable_expand(v1, 1, [R, S, T], "barg").

       This will add to the 2 x 3 viewable a third row, named "barg".

       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
       	               array([fixed, flexible], any)), 
       viewable_expand(v1, 2, [Q, P], "zatch").

       This will add to the 2 x 3 viewable a fourth column, named "zatch".


</PRE>
<H2>See Also</H2>
<A HREF="../../lib/viewable/viewable_expand-3.html">viewable_expand / 3</A>, <A HREF="../../lib/viewable/viewable_create-4.html">viewable_create / 4</A>, <A HREF="../../lib/viewable/viewable_size-2.html">viewable_size / 2</A>, <A HREF="../../lib/viewable/viewable_type-2.html">viewable_type / 2</A>
</BODY></HTML>
